<?php
/**
* Tree Interface
* 
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* 
* @copyright Copyright (c) 2008-2009 Ne8, LLC <josh.ribakoff@gmail.com>
* @license New BSD License
* @version 0.1
* @category Shuffler
* @package Shuffler_Model
* @subpackage Tree
*/
interface Shuffler_Model_Tree_Interface
{
    /**
    * Create a new node in the tree
    * 
    * @param string
    * @return Shuffler_Model_Tree_Node_Interface
    */
    public function newNode( $name );
    
    /**
    * Get the current node in the tree
    * 
    * @retrun Shuffler_Model_Tree_Node_Interface
    */
    public function getCurrent();
    
    /**
    * Set the current node in the tree
    * 
    * @param Shuffler_Node_Interface to set as the current node
    */
    public function setCurrent( Shuffler_Model_Tree_Node_Interface $node );
    
    /**
    * Add a child node
    * 
    * @param Shuffler_Model_Tree_Node_Interface to add
    * @bool optional $setCurrent | set this node as the current node so subsequent nodes become successors
    */
    public function addChild( Shuffler_Model_Tree_Node_Interface $node, $setCurrent = false);
    
    /**
    * Get the parent node
    * 
    * @return Shuffler_Model_Tree_Node_Interface
    */
    function getParent();
    
    /**
    * Reset the tree so the current node is set to the root node
    */
    public function reset();
    
    /**
    * Set the root of the tree to a given node
    * 
    * optionally sets the current tree node
    * to this new root node, enabled by default (opt-out functionality)
    * 
    * @param Shuffler_Model_Tree_Node_Interface new root node
    * @param boolean wether or not to set the new root node to this node, defaults functionality
    */
    public function setRoot( Shuffler_Model_Tree_Node_Interface $root, $setCurrent = true );
    
}